<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>env</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_001_014_567">&nbsp;</a>NAME</h4><blockquote>
env - set the environment for command invocation
</blockquote><h4><a name = "tag_001_014_568">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

env <b>[</b>-i<b>][</b><i>name</i>=<i>value</i><b>]</b>... <b>[</b><i>utility </i><b>[</b><i>argument</i>...<b>]]</b>

env <b>[</b>-<b>][</b><i>name</i>=<i>value</i><b>]</b>... <b>[</b><i>utility </i><b>[</b><i>argument</i>...<b>]]</b>
</code>
</pre>
</blockquote><h4><a name = "tag_001_014_569">&nbsp;</a>DESCRIPTION</h4><blockquote>
The
<i>env</i>
utility will obtain the current environment,
modify it according to its arguments,
then invoke the utility named by the
<i>utility</i>
operand with the modified environment.
<p>
Optional arguments will be passed to
<i>utility</i>.
<p>
If no
<i>utility</i>
operand is specified,
the resulting environment will be written to the standard output, with one
<i>name=value</i>
pair per line.
</blockquote><h4><a name = "tag_001_014_570">&nbsp;</a>OPTIONS</h4><blockquote>
The
<i>env</i>
utility supports the <b>XBD</b> specification, <a href="../xbd/utilconv.html#usg"><b>Utility Syntax Guidelines</b>&nbsp;</a> ,
except for its non-standard usage of "-".
<p>
The following options are supported:
<dl compact>

<dt><b>-i</b><dd>
<dt><b>-</b><dd>
Invoke
<i>utility</i>
with exactly the environment specified by
the arguments; the inherited environment will be ignored completely.

</dl>
</blockquote><h4><a name = "tag_001_014_571">&nbsp;</a>OPERANDS</h4><blockquote>
The following operands are supported:
<dl compact>

<dt><i>name=value</i><dd>
Arguments of the form
<i>name=value</i>
modify the execution environment,
and are placed into the inherited environment
before the
<i>utility</i>
is invoked.

<dt><i>utility</i><dd>The name of the utility to be invoked.
If the
<i>utility</i>
operand names any of the special built-in utilities in
<xref href=sbi><a href="chap2.html#tag_001_014">
Special Built-in Utilities
</a></xref>,
the results are undefined.

<dt><i>argument</i><dd>
A string to pass as an argument for the invoked utility.

</dl>
</blockquote><h4><a name = "tag_001_014_572">&nbsp;</a>STDIN</h4><blockquote>
Not used.
</blockquote><h4><a name = "tag_001_014_573">&nbsp;</a>INPUT FILES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_001_014_574">&nbsp;</a>ENVIRONMENT VARIABLES</h4><blockquote>
The following environment variables affect the execution of
<i>env</i>:
<dl compact>

<dt><i>LANG</i><dd>Provide a default value for the internationalisation variables
that are unset or null.
If
<i>LANG</i>
is unset or null, the corresponding value from the
implementation-dependent default locale will be used.
If any of the internationalisation variables contains an invalid setting, the
utility will behave as if none of the variables had been defined.

<dt><i>LC_ALL</i><dd>
If set to a non-empty string value,
override the values of all the other internationalisation variables.

<dt><i>LC_CTYPE</i><dd>
Determine the
locale for the interpretation of sequences of bytes of text data as
characters (for example, single- as opposed to multi-byte characters
in arguments).

<dt><i>LC_MESSAGES</i><dd>
Determine the locale that should be used to affect
the format and contents of diagnostic
messages written to standard error.

<dt><i>NLSPATH</i><dd>
Determine the location of message catalogues
for the processing of
<i>LC_MESSAGES .
</i>
<dt><i>PATH</i><dd>Determine the location of the
<i>utility</i>,
as described in
the <b>XBD</b> specification, <a href="../xbd/envvar.html"><b>Environment Variables</b>&nbsp;</a> .
If
<i>PATH</i>
is specified as a
<i>name=value</i>
operand to
<i>env</i>,
the
<i>value</i>
given will be used in the search for
<i>utility</i>.

</dl>
</blockquote><h4><a name = "tag_001_014_575">&nbsp;</a>ASYNCHRONOUS EVENTS</h4><blockquote>
Default.
</blockquote><h4><a name = "tag_001_014_576">&nbsp;</a>STDOUT</h4><blockquote>
If no
<i>utility</i>
operand is specified, each
<i>name=value</i>
pair in the resulting environment will be written in the form:
<p><code>
<tt>"%s=%s\n"</tt>, &lt;<i>name</i>&gt;,
&lt;<i>value</i>&gt;
</code>
<p>
If the
<i>utility</i>
operand is specified, the
<i>env</i>
utility will not write to standard output.
</blockquote><h4><a name = "tag_001_014_577">&nbsp;</a>STDERR</h4><blockquote>
Used only for diagnostic messages.
</blockquote><h4><a name = "tag_001_014_578">&nbsp;</a>OUTPUT FILES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_001_014_579">&nbsp;</a>EXTENDED DESCRIPTION</h4><blockquote>
None.
</blockquote><h4><a name = "tag_001_014_580">&nbsp;</a>EXIT STATUS</h4><blockquote>
If the
<i>utility</i>
utility is invoked, the exit status of
<i>env</i>
will be the
exit status of
<i>utility;</i>
otherwise, the
<i>env</i>
utility will exit with one of the following values:
<dl compact>

<dt>0<dd>The
<i>env</i>
utility completed successfully.

<dt>1-125<dd>An error occurred in the
<i>env</i>
utility.

<dt>126<dd>The utility specified by
<i>utility</i>
was found but could not be invoked.

<dt>127<dd>The utility specified by
<i>utility</i>
could not be found.

</dl>
</blockquote><h4><a name = "tag_001_014_581">&nbsp;</a>CONSEQUENCES OF ERRORS</h4><blockquote>
Default.
</blockquote><h4><a name = "tag_001_014_582">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
The
<i><a href="command.html">command</a></i>,
<i>env</i>,
<i><a href="nice.html">nice</a></i>,
<i><a href="nohup.html">nohup</a></i>,
<i><a href="time.html">time</a></i>
and
<i><a href="xargs.html">xargs</a></i>
utilities have been specified to use
exit code 127 if an error occurs so that
applications can distinguish
&quot;failure to find a utility&quot; from &quot;invoked utility exited
with an error indication&quot;.
The value 127 was chosen because it is not commonly used for other meanings;
most utilities use small values for &quot;normal error conditions&quot; and
the values above 128 can be confused with termination due to receipt of a
signal.
The value 126
was chosen in a similar manner to indicate that the utility
could be found, but not invoked.
Some scripts produce meaningful error messages
differentiating the 126 and 127 cases.
The distinction between exit codes 126 and 127 is based
on KornShell practice that uses 127 when all attempts to
<i>exec</i>
the utility fail with
[ENOENT],
and uses 126 when any attempt to
<i>exec</i>
the utility fails for any other reason.
<p>
Historical implementations of the
<i>env</i>
utility use the <b>XSH</b> specification
<i><a href="../xsh/execvp.html">execvp()</a></i>
or
<i><a href="../xsh/execlp.html">execlp()</a></i>
functions
to invoke the specified utility; this provides
better performance and keeps users from having to escape characters with
special meaning to the shell.
Therefore, shell functions, special
built-ins and built-ins that are only provided by the shell are not found.
</blockquote><h4><a name = "tag_001_014_583">&nbsp;</a>EXAMPLES</h4><blockquote>
The following command:
<pre>
<code>
env -i PATH=/mybin mygrep xyz myfile
</code>
</pre>
invokes the command
<i>mygrep</i>
with a new
<i>PATH</i>
value as the only entry in its environment.
In this case,
<i>PATH</i>
is used to locate
<i>mygrep</i>,
which then must reside in
<b>/mybin</b>.
</blockquote><h4><a name = "tag_001_014_584">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
None.
</blockquote><h4><a name = "tag_001_014_585">&nbsp;</a>SEE ALSO</h4><blockquote>
<xref href=parms><a href="chap2.html#tag_001_005">
Parameters and Variables
</a></xref>.
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>
